更新提示：扩展更新后在页内弹出本次变更说明 - #362
Merged
Merged
Conversation
设计经四轮 grilling 定案，两处难以逆转的取舍记入 ADR。 形态（ADR-0001）：content script 在 document_end 以 shadow DOM 模态弹出， 即用户打开新页面的瞬间，而不是新开标签页。扩展更新由浏览器静默完成， 新标签页会在用户不在场时创建，回来后最容易被顺手关掉。首装欢迎页维持 独立标签页不变，两者共存不合并。 版本（ADR-0002）：不建 CHANGELOG.md、不打 tag，src/changelog/data.ts 里 写了条目的版本即上架版本。本项目每个 fix PR 都 bump 末位版本号，内部版本 变动频繁而只有阶段性完成才上架 —— 此法把「哪个版本值得打扰用户」与「你写 没写更新说明」合并成同一个动作，不可能弹了却没内容或有内容却没弹。校验挂 在 pnpm zip 而非 pnpm build：日常构建时当前版本本就是没有条目的内部版本。 行为：显示出来即算已读（点 X 也算），状态存 sync 独立 key pt-changelog， 不并入 pt-settings 以免被配置导出带走。多标签页并发由 background 串行仲裁， 只放行一个；显示权在发放时即标记已读，渲染失败则 clearSeen 回滚，否则该 上架版本会被永久跳过。iframe、名单中被禁用翻译的站点、开发构建、无条目的 内部版本一律不弹；首装时标记当前版本已读，新用户看到的是欢迎页。 界面色值全部取自 tokens.css 令牌。底部只放大 GitHub 求 star，不显示 star 数以免为一个数字新增 api.github.com 权限。赞赏、文档、社交三块本版隐藏， 以数据驱动表达（数组留空或注释数据行），渲染逻辑照常参与类型检查。 测试：五个纯逻辑 seam 共 25 个用例（版本查询、语言选择、已读状态、本地 预筛、并发仲裁），src/changelog/** 纳入覆盖率门槛 90；modal.ts 属 DOM 渲染，与 src/ui/** 同例外。 Co-Authored-By: zhexuancai-uts <261878103+zhexuancai-uts@users.noreply.github.com>
内容：2.0.66 的条目由一条扩到十条，分新功能 / 改进 / 修复三组。新功能 写对照阅读、六个触发入口、多引擎故障切换与更新提示本身；改进写网页 适配、译文样式、最小权限；修复写三条用户真能感知的：单页应用上自动 冒出译文、shadow DOM 内折叠内容漏翻、导入配置残留本机模型名。 三语各自撰写而非转译 —— 繁体用台港词汇（擴充功能 / 快速鍵 / 匯入 / 預設 / 網路），英文按英文行文重写而不是把中文句式搬过去。 核实后剔除一条：设置页「测试连接」早在 v0.6.1 就存在，#321-#323 只是 把探测逻辑统一到公共入口，属内部重构，写进更新说明会误导用户以为是 新功能。同理，2.0 之后那六十余次提交绝大多数是编排模块与引擎的内部 迁移，用户无从感知，一概不写。 分隔符：标题与描述之间原本硬编码全角冒号，英文用户会看到 「Side-by-side reading：The original…」这样的混搭。改为按语言取值 （中文全角冒号，英文破折号）。此问题由渲染真实数据的预览发现。 Co-Authored-By: zhexuancai-uts <261878103+zhexuancai-uts@users.noreply.github.com>
首装靠 markSeen 挡住更新提示，但 storage 写入是异步的：落盘之前 content script 的 claim 会读到「未读」而拿到显示权，新用户于是在装完 打开的第一个页面上看到「更新内容」弹窗，而它的全屏遮罩还会挡住页面。 窗口很窄，本地 e2e-core 跑两遍都侥幸没触发，但这是竞态赢了而不是不 存在 —— CI 机器负载与本地不同，翻转即表现为偶发红灯，且这类 flaky 查起来很痛。 onInstalled 的监听器现在同步置位内存标志，Service Worker 单线程保证 它跑在任何 claim 消息之前，窗口归零；storage 落盘照旧，SW 回收后由它 接手判定。补两个用例覆盖「标志已置位但 markSeen 尚未落盘」这一瞬。 Co-Authored-By: zhexuancai-uts <261878103+zhexuancai-uts@users.noreply.github.com>
样式：默认从「黄铜色左边线 + 半透明」改为纯半透明，压低译文存在感、 不打断原文阅读节奏；原样式改名 border（中文「左边线」）挪到预设列表 末尾；原 fade 与新 default 效果完全重合，删除。预设总数仍是六种。 存储迁移：选过 fade 的用户，存储里躺着一个不再存在的 id。放行会让 applyStyle 挂上没有任何 CSS 规则的类名 —— 译文变成完全不透明，用户只 会觉得「我明明选了半透明」。merge 是读取路径的单点，迁移放在那里： fade 迁 default（观感不变），认不出的值一律回落 default。 styles/shadow.ts 里有同一套预设的第二份拷贝（:host-context 变体）， 一并同步 —— 漏改会让 shadow DOM 内的译文样式失效，而那正是本扩展 用来对付现代站点的主要手段。 popup：页脚新增「汇报问题」，走 chrome.tabs.create 打开 GitHub 新建 issue 页。不用 window.open —— popup 失焦即关，会连自己一起没掉。 同步更新说明与上架材料：changelog 加两条（默认样式变化、汇报问题 入口），样式清单里的「半透明」改为「左边线」；商店中英描述一并改。 版本 2.0.66 → 2.0.67 —— 2.0.66 的包已经交付过，代码变了必须换号， 否则会出现两个内容不同的同名包。 Co-Authored-By: zhexuancai-uts <261878103+zhexuancai-uts@users.noreply.github.com>
商店说明框不渲染 Markdown，旧文案里的 ## 与 ** 会原样显示成井号 和星号。三份描述改为纯文本，并在文件开头标明简短说明 132 字符、 详细说明 16000 字符的贴入位置。 内容按重构版实际行为重写：六个翻译入口、单段与整页显示模式可分开 设置、引擎按优先级容错切换且跳过不支持目标语言的引擎、Shadow DOM 与同源 iframe 穿透、更新说明只弹一次。新增 description-zh_TW.md。 permissions-justification.md 记录 Privacy practices 分页的填写内容 （英文，审核员会对照 manifest 核验）：storage 的四项用途、 contextMenus 仅注册一个 selection 菜单项、七个引擎端点逐条对应， 以及 Remote code 与 Data usage 两页的选法。改动权限后须同步此文件。 data.ts 顺带统一繁中「左邊線」的用词。 Co-Authored-By: zhexuancai-uts <261878103+zhexuancai-uts@users.noreply.github.com>
Teeeeeeeerry
added a commit
that referenced
this pull request
Sep 3, 2026
#362 在 GitHub 上以 squash 方式合入，main 得到 627ca57；本分支的 原始提交 26ae94b 的 SHA 与之不同，Git 两边都视为「新增」同名文件， 于是 changelog 模块 7 个文件与 3 份商店描述全部 add/add 冲突。 10 个冲突文件一律取本分支版本。取之前逐个比对过 main 与分支的内容： changelog 七个文件的差异只有本次加的版权头（data.ts 是 6 行新增、 0 行删除），三份商店描述的差异只有结尾那句许可声明。分支版本是 main 版本的超集，没有 main 独有的内容被丢弃。 合并后与 main 的差异仍是 81 文件 / +1165 / -6，与合并前的两点 diff 逐字一致。 Co-Authored-By: zhexuancai-uts <261878103+zhexuancai-uts@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
问题
扩展更新后，用户无从知道这一版改了什么。仓库既没有 CHANGELOG.md 也没有 git tag，「哪个版本真正上架过」只存在于维护者记忆里。
方案
设计经四轮 grilling 定案，两处难以逆转的取舍记入 ADR。
形态（ADR-0001） —— content script 在
document_end以 shadow DOM 模态弹出，即用户打开新页面的瞬间，而不是新开标签页。扩展更新由浏览器静默完成，新标签页会在用户不在场时创建，回来后最容易被顺手关掉。首装欢迎页维持独立标签页不变，两者共存不合并。版本（ADR-0002） —— 不建 CHANGELOG.md、不打 tag，
src/changelog/data.ts里写了条目的版本即上架版本。本项目每个 fix PR 都 bump 末位版本号，内部版本变动频繁而只有阶段性完成才上架，此法把「哪个版本值得打扰用户」与「你写没写更新说明」合并成同一个动作，不可能弹了却没内容或有内容却没弹。校验挂在pnpm zip而非pnpm build：日常构建时当前版本本就是没有条目的内部版本。行为
pt-changelog，不并入pt-settings以免被配置导出带走clearSeen回滚，否则该上架版本会被永久跳过onInstalled同步置位内存标志 + 异步落盘。只靠落盘会留下竞态窗口，新用户可能在装完打开的第一个页面被全屏遮罩挡住tokens.css令牌；底部只放大 GitHub 求 star，不显示 star 数以免为一个数字新增api.github.com权限更新说明内容
2.0.66条目十条，分新功能 / 改进 / 修复三组，三语各自撰写而非转译（繁体用台港词汇，英文按英文行文重写）。核实后剔除一条：设置页「测试连接」早在 v0.6.1 就存在，#321-#323 只是内部重构，写进去会误导用户以为是新功能。验证
本地跑通全部四个 CI job：
check-commit-conventions.shtypechecktest:coveragesrc/changelog/**覆盖率 93.18%（门槛 90）build+test:verify-buildtest:artifactstest:e2e:core+verify-e2e-activetest:e2e --grep @mac上架校验先验红灯（CHANGELOG 为空时
pnpm zip拒绝）再转绿。弹窗视觉以真实数据渲染预览逐条核对，并借此发现英文条目的分隔符混用了中文全角冒号，已改为按语言取值。已知取舍
本次是首次上架，商店里没有老用户，而首装会自动标记已读 —— 因此
2.0.66这十条说明本次不会被任何人看到。维护者已确认维持现状（更新提示只服务老用户），下次上架时写新条目即可。